/**
 * <p>Copyright (c) Snail Game 2014</p>
 */
package com.snail.billing.sso;

/**   
 * @Title: TicketRetriever.java 
 * @Description: 
 * Retrieve service ticket for specified service URI.
 * 
 * ST: Service Ticket, it represents user for access service URI. It means that user login principle
 * 
 * TGT: Ticket Granting Ticket, it is used to retrieve service ticket, SSO server generate one-time ST for service URI
 * 
 * Mobile application can call {@link TicketRetriever.getTicketGrantingTicket} cache the TGT to generate one-time ST.
 * Mobile application retrieve ST with TGT from SSO server, before user access service URI.
 * 
 * If user access a web site resource, application post TG as parameter when open browser.
 * It looks like: http://passport.woniu.com/basic?ticket=ST-18-vbahguenwVXwC0vGIgEb-sso
 * 
 * SSO server will validate this TG for this service URI, if TG is valid, SSO server redirects user to
 * service URI by add HTTP code 302.
 * Step 1: Mobile application call service URI with TG by web browser.
 * http://passport.woniu.com/basic?ticket=ST-18-vbahguenwVXwC0vGIgEb-sso
 * Step 2: SSO server validates TG, and redirects user to service URI.
 * http://passport.woniu.com/basic/;jsessionid=4910429FC577875A34A5318ECF796757
 * 
 * @author Wang Junxiang
 * @date 2014-8-29
 * @version 1.0 
 * @since 1.0  
 */
public interface TicketRetriever {

	public static final String USERNAME = "username";
	public static final String PASSWORD = "password";
	public static final String SERVICE_URI = "service";
	
	/**
	 * The entry method for get service ticket
	 * In general, client call this method to retrieve service ticket from SSO server.
	 * If client need to cache TGT(Ticket Granting Ticket), client should call {@link getTicketGrantingTicket} to
	 * get the ticket, and manual call {@link getServiceTicket} to get service ticket.
	 * 
	 * @param ssoServer
	 * @param username
	 * @param password
	 * @param serviceUri
	 * @return
	 * @throws TicketRetrieveException
	 */
	String getTicket(final String ssoServer, final String username, final String password, final String serviceUri) throws TicketRetrieveException;
	
	/**
	 * Get ticket granting ticket from SSO server
	 * @param ssoServer
	 * @param username
	 * @param password
	 * @return
	 * @throws TicketRetrieveException
	 */
	String getTicketGrantingTicket(final String ssoServer, final String username, final String password) throws TicketRetrieveException;
	
	/**
	 * Get service ticket for specified service from SSO server
	 * @param ssoServer
	 * @param ticketGrantingTicket
	 * @param serviceUri
	 * @return
	 * @throws TicketRetrieveException
	 */
	String getServiceTicket(final String ssoServer, final String ticketGrantingTicket, final String serviceUri) throws TicketRetrieveException;
	
	/**
	 * Set connection for communicated with SSO server
	 * @param connection
	 */
	void setConnection(Connection connection);
}
